👤 API de Usuários - Documentação Completa

📋 Visão Geral

A API de Usuários é responsável por toda a gestão de usuários no sistema CordenaAi, incluindo consulta, verificação de dados, atribuição de funções e gerenciamento de informações pessoais. Esta API permite buscar usuários por diferentes identificadores, verificar dados únicos como CPF e email, consultar funções por contexto e gerenciar informações como nome social.

🎯 Endpoints Disponíveis

📝 Consulta de Usuários

1. GET /api/Usuarios/{identificador}

Obter Usuário por Identificador

2. GET /api/Usuarios

Listar Todos os Usuários

🔍 Verificação de Dados

3. GET /api/Usuarios/verificar-cpf/{cpf}

Verificar CPF

4. GET /api/Usuarios/verificar-email/{email}

Verificar Email

5. GET /api/Usuarios/verificar-celular/{celular}

Verificar Celular

🎭 Gestão de Funções

6. GET /api/Usuarios/{identificador}/funcoes/{contexto}

Consultar Funções por Contexto

7. POST /api/Usuarios/{identificador}/atribuir-funcao

Atribuir Função a Usuário

📝 Gestão de Informações Pessoais

8. PUT /api/Usuarios/{identificador}/nome-social

Atualizar Nome Social

9. GET /api/Usuarios/teste-nome-social/{identificador}

Testar Campo Nome Social

🔧 Modelo de Dados

Estrutura do Usuário

{
  "id": "string",
  "userName": "string",
  "nome": "string",
  "nomeSocial": "string",
  "email": "string",
  "cpf": "string",
  "celular": "string",
  "dataNascimento": "datetime",
  "genero": "string",
  "foto": "string",
  "status": "boolean",
  "dataCadastro": "datetime",
  "dataAtualizacao": "datetime"
}

Estrutura de Funções do Usuário

{
  "usuarioId": "string",
  "usuarioNome": "string",
  "contexto": "string",
  "funcoes": [
    {
      "id": "int",
      "nome": "string",
      "descricao": "string",
      "contexto": "string"
    }
  ]
}

Estrutura para Atribuição de Função

{
  "funcaoId": "int",
  "contexto": "string",
  "turmaId": "int"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Consulta de Usuário por Identificador Flexível

GET /api/Usuarios/[email protected]
Authorization: Bearer {token}

2. Verificação de CPF em Formulário

GET /api/Usuarios/verificar-cpf/123.456.789-00
Authorization: Bearer {token}

3. Consulta de Funções por Contexto

GET /api/Usuarios/user123/funcoes/turma
Authorization: Bearer {token}

4. Atribuição de Função

POST /api/Usuarios/user123/atribuir-funcao
Content-Type: application/json
Authorization: Bearer {token}

{
  "funcaoId": 1,
  "contexto": "turma",
  "turmaId": 5
}

5. Atualização de Nome Social

PUT /api/Usuarios/user123/nome-social
Content-Type: application/json
Authorization: Bearer {token}

{
  "nomeSocial": "João"
}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo de Verificação de Dados

  1. Validação de dados no backend pela própria API
  2. GET /api/Usuarios/verificar-cpf/{cpf} para verificar CPF
  3. GET /api/Usuarios/verificar-email/{email} para verificar email
  4. Retorno das informações de existência
  5. Cache dos resultados para próximas verificações

Fluxo de Consulta de Funções

  1. GET /api/Usuarios/{identificador}/funcoes/{contexto} com parâmetros
  2. Busca do usuário por identificador flexível
  3. Consulta das funções no contexto específico
  4. Retorno das funções e papéis do usuário
  5. Cache dos resultados para próximas consultas

Fluxo de Atribuição de Função

  1. Validação do usuário e função
  2. POST /api/Usuarios/{identificador}/atribuir-funcao com dados
  3. Verificação de relacionamentos necessários
  4. Atribuição da função no contexto
  5. Notificação de confirmação

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi